/*
 * Copyright 2012-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.task;

import java.time.Duration;
import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.Set;

import org.springframework.boot.context.properties.PropertyMapper;
import org.springframework.scheduling.TaskScheduler;
import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;
import org.springframework.util.Assert;
import org.springframework.util.CollectionUtils;

/**
 * 用于配置和创建 {@link TaskScheduler} 的构建器。提供设置常用 {@link ThreadPoolTaskScheduler} 配置的便捷方法。
 * 对于高级配置，建议使用 {@link TaskSchedulerCustomizer}。
 * <p>
 * 在典型的 Spring Boot 自动配置应用中，此构建器作为一个 bean 提供，
 * 并且可以在需要 {@link TaskScheduler} 时注入使用。
 *
 * @author Stephane Nicoll
 * @since 2.1.0
 */
public class TaskSchedulerBuilder {

	private final Integer poolSize;

	private final Boolean awaitTermination;

	private final Duration awaitTerminationPeriod;

	private final String threadNamePrefix;

	private final Set<TaskSchedulerCustomizer> customizers;

	public TaskSchedulerBuilder() {
		this.poolSize = null;
		this.awaitTermination = null;
		this.awaitTerminationPeriod = null;
		this.threadNamePrefix = null;
		this.customizers = null;
	}

	public TaskSchedulerBuilder(Integer poolSize, Boolean awaitTermination, Duration awaitTerminationPeriod,
			String threadNamePrefix, Set<TaskSchedulerCustomizer> taskSchedulerCustomizers) {
		this.poolSize = poolSize;
		this.awaitTermination = awaitTermination;
		this.awaitTerminationPeriod = awaitTerminationPeriod;
		this.threadNamePrefix = threadNamePrefix;
		this.customizers = taskSchedulerCustomizers;
	}

	/**
	 * 设置允许的最大线程数。
	 * @param poolSize 要设置的线程池大小
	 * @return 一个新的构建器实例
	 */
	public TaskSchedulerBuilder poolSize(int poolSize) {
		return new TaskSchedulerBuilder(poolSize, this.awaitTermination, this.awaitTerminationPeriod,
				this.threadNamePrefix, this.customizers);
	}

	/**
	 * 设置执行器在关闭时是否应等待计划任务完成，期间不打断正在运行的任务，并执行队列中的所有任务。
	 * @param awaitTermination 指示执行器是否需要在关闭时等待任务完成
	 * @return 一个新的构建器实例
	 * @see #awaitTerminationPeriod(Duration)
	 */
	public TaskSchedulerBuilder awaitTermination(boolean awaitTermination) {
		return new TaskSchedulerBuilder(this.poolSize, awaitTermination, this.awaitTerminationPeriod,
				this.threadNamePrefix, this.customizers);
	}

	/**
	 * 设置执行器在关闭时阻塞的最长时间。设置后，执行器在关闭时会阻塞，以等待剩余任务完成执行，
	 * 这样容器的其余部分才能继续关闭。如果剩余任务可能需要访问容器管理的其他资源，这一点尤其有用。
	 * @param awaitTerminationPeriod 要设置的等待终止时间
	 * @return 一个新的构建器实例
	 */
	public TaskSchedulerBuilder awaitTerminationPeriod(Duration awaitTerminationPeriod) {
		return new TaskSchedulerBuilder(this.poolSize, this.awaitTermination, awaitTerminationPeriod,
				this.threadNamePrefix, this.customizers);
	}

	/**
	 * 设置新创建线程名称的前缀。
	 * @param threadNamePrefix 要设置的线程名前缀
	 * @return 一个新的构建器实例
	 */
	public TaskSchedulerBuilder threadNamePrefix(String threadNamePrefix) {
		return new TaskSchedulerBuilder(this.poolSize, this.awaitTermination, this.awaitTerminationPeriod,
				threadNamePrefix, this.customizers);
	}

	/**
	 * 设置应应用于 {@link ThreadPoolTaskScheduler} 的 {@link TaskSchedulerCustomizer}。
	 * 自定义器按添加顺序依次应用于构建器配置后。设置此值将替换之前配置的所有自定义器。
	 * @param customizers 要设置的自定义器
	 * @return 一个新的构建器实例
	 * @see #additionalCustomizers(TaskSchedulerCustomizer...)
	 */
	public TaskSchedulerBuilder customizers(TaskSchedulerCustomizer... customizers) {
		Assert.notNull(customizers, "Customizers must not be null");
		return customizers(Arrays.asList(customizers));
	}

	/**
	 * 设置应应用于 {@link ThreadPoolTaskScheduler} 的 {@link TaskSchedulerCustomizer}。
	 * 自定义器按添加顺序依次应用于构建器配置后。设置此值将替换之前配置的所有自定义器。
	 * @param customizers 要设置的自定义器集合
	 * @return 一个新的构建器实例
	 * @see #additionalCustomizers(TaskSchedulerCustomizer...)
	 */
	public TaskSchedulerBuilder customizers(Iterable<TaskSchedulerCustomizer> customizers) {
		Assert.notNull(customizers, "Customizers must not be null");
		return new TaskSchedulerBuilder(this.poolSize, this.awaitTermination, this.awaitTerminationPeriod,
				this.threadNamePrefix, append(null, customizers));
	}

	/**
	 * 添加应应用于 {@link ThreadPoolTaskScheduler} 的 {@link TaskSchedulerCustomizer}。
	 * 自定义器会在构建器配置应用之后，按添加顺序依次应用。
	 * @param customizers 要添加的自定义器
	 * @return 一个新的构建器实例
	 * @see #customizers(TaskSchedulerCustomizer...)
	 */
	public TaskSchedulerBuilder additionalCustomizers(TaskSchedulerCustomizer... customizers) {
		Assert.notNull(customizers, "Customizers must not be null");
		return additionalCustomizers(Arrays.asList(customizers));
	}

	/**
	 * 添加应应用于 {@link ThreadPoolTaskScheduler} 的 {@link TaskSchedulerCustomizer}。
	 * 自定义器会在构建器配置应用之后，按添加顺序依次应用。
	 * @param customizers 要添加的自定义器集合
	 * @return 一个新的构建器实例
	 * @see #customizers(TaskSchedulerCustomizer...)
	 */
	public TaskSchedulerBuilder additionalCustomizers(Iterable<TaskSchedulerCustomizer> customizers) {
		Assert.notNull(customizers, "Customizers must not be null");
		return new TaskSchedulerBuilder(this.poolSize, this.awaitTermination, this.awaitTerminationPeriod,
				this.threadNamePrefix, append(this.customizers, customizers));
	}

	/**
	 * 构建一个新的 {@link ThreadPoolTaskScheduler} 实例并使用该构建器进行配置。
	 * @return 一个已配置的 {@link ThreadPoolTaskScheduler} 实例。
	 * @see #configure(ThreadPoolTaskScheduler)
	 */
	public ThreadPoolTaskScheduler build() {
		return configure(new ThreadPoolTaskScheduler());
	}

	/**
	 * 使用该构建器配置提供的 {@link ThreadPoolTaskScheduler} 实例。
	 * @param <T> 任务调度器的类型
	 * @param taskScheduler 要配置的 {@link ThreadPoolTaskScheduler} 实例
	 * @return 已配置的任务调度器实例
	 * @see #build()
	 */
	public <T extends ThreadPoolTaskScheduler> T configure(T taskScheduler) {
		PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
		map.from(this.poolSize).to(taskScheduler::setPoolSize);
		map.from(this.awaitTermination).to(taskScheduler::setWaitForTasksToCompleteOnShutdown);
		map.from(this.awaitTerminationPeriod).asInt(Duration::getSeconds).to(taskScheduler::setAwaitTerminationSeconds);
		map.from(this.threadNamePrefix).to(taskScheduler::setThreadNamePrefix);
		if (!CollectionUtils.isEmpty(this.customizers)) {
			this.customizers.forEach((customizer) -> customizer.customize(taskScheduler));
		}
		return taskScheduler;
	}

	private <T> Set<T> append(Set<T> set, Iterable<? extends T> additions) {
		Set<T> result = new LinkedHashSet<>((set != null) ? set : Collections.emptySet());
		additions.forEach(result::add);
		return Collections.unmodifiableSet(result);
	}

}
